This is a library of screen fading operations which can be used to make your games more professional looking. Not only does the clut_fade library let you fade to and from black, but it also provides routines to fade to and from a specific color or a specific clut. It also provides some control over which monitors are faded. Demo application, library, and cource code are included.
fade_to_black function written by Jonas Englund, modified by Mark Womack for multiple monitors.
fade_to_clut function written by Macneil Shonle.
Pascal version written by Christian Franz.
Clut Fade 1.0 was posted by Ken Long (AOL: KenLong, Internet: kenlong@aol.com).
Release notes for earlier versions are also included in this file.
Disclaimer
This software is considered Public Domain. You are free to use it in any manner you wish. You are free to upload it to your favorite online service, but you must post it with the accompanying readme and description files. If you use or appreciate it, please let us know!! We all love to get email. See the addresses below.
This software is offered 'as is'. The authors are not responsible for any damages caused by bugs or defects that might be lurking. But if it blows up your monitor, please let us know. If you find any bugs, problems, enhancements, please contact us.
What's New?
• A bug was bought to our attention by David Padilla. When using the fade routines, the ctSeed of the faded gDevice was being changed from the value it had before the fade took place. This dramatically slows down subsequent calls to CopyBits as it compares both the source and destination color tables (because now the ctSeed's are different) to see if it needs to do any color mapping. So, we made changes to the code to restore the ctSeed to the original value. If you use the fade_to_black or fade_to_color routines, this is automatic. If you use the fade_to_clut routine, the ctSeed of the passed in clut is used, so get a copy of the original clut (using copy_gdevice_clut), fade to your new clut (which has a different ctSeed value), then fade back to the original clut. As long as you don't change your original copy, you will be fine. The FadeTester application source shows an example of this in the "Fade to Inverse" action. Many thanks to David Padilla for the find! If we had t-shirts, he'd get one. If anyone has more to add to this, or thinks the fix is bogus, please let us know.
• Also fixed a bug in the Fade Tester application. For the 'Fade Thru Rainbow' action, clut's loaded in from the resource are resized so that the number of colors they contain match the number of colors supported by the graphic device. The code to set the handle size of the color table was completely wrong. Replaced it code that calculates the correct size.
Both the C and Pascal versions have the fixes. We've made an effort to keep them in sync! Thanks to Christian for testing the Pascal changes.
Other Items of Interest
• Some time back someone reported a bug with the clut_fade library. Something to do with the wrong colors in the clut. Neither Mac nor myself can remember exactly the bug or what the fix was and we don't think it made it into a version. So, if you encounter a similar bug or you're that person reading this, please send us some email and let us know so we can fix it.
• Kenneth Worley has created some C++ classes that are based on the clut_fade routines. Sounds like he has added some other neat enhancements. If you are interested, you can reach him at: AOL: KNEworley, Internet: KNEworley@aol.com.
WE WANT TO HEAR FROM YOU!!!!
If there something you want this library to do, or you have a modification you'd like to share with the world, or you find a bug, or just think clut_fade is cool please contact us at the following addresses:
Mark Womack - AOL: MarkWomack, Internet: markwomack@aol.com
The only change for this version is the Pascal version written by Christian Franz. This isn't a C library with pascal headers. This is the REAL thing. A complete port of the C code into Pascal. So, you Pascal users should be very happy and thank Christian for doing a great job! His email address is listed below and see the ReadMe for the Pascal version.
Because of the versions in different languages, the files have been seperated into two folders. One folder for C and another for Pascal. Other than that, the C source is the same as version 1.3.
Not much has changed. Just some upgrades to MetroWerks and a couple changes in Fade Tester.
• Upgraded to MetroWerks 6.0 for both the clut_fade library and the FadeTester demo. However, THINK C library and projects are still included.
• FadeTester now uses "Jim's CDEFs v1.50" (written by Jim Stout) for the controls in the dialog. Also added a control for the fade speed. Jim's CDEFs is very cool.
The biggest addition to the Clut Fade library is the fade_to_clut function written by Macneil Shonle. At the end of the 1.1 release notes I mentioned that Ken Long wanted to be able to fade to other colors besides black. Well, Macneil sent me this cool little piece of code that does just that and more. It actually takes a new clut as a parameter, so you can fade to an entirely different color set. This has the potential for some really neat effects, only a couple of which are explored in the Fade Tester application. Take a look at the code, it is very cool.
Other changes are:
• Created a fade_to_color() function which in basically a wrapper for the fade_to_clut() function. If you want to fade to a single color, not an entire clut, then use this routine. It creates a single color clut on the fly so you don’t have to load it from a ‘clut’ resource. Examples of both are in the Fade Tester application.
• I tried to make the library 'Pascal friendly' by making the public functions pascal compatible. I created a .lib file that is compatible with Think Pascal and Chris Sollitto was kind enough to create and test a Pascal interface file. You can find both in 'For Pascal' folder.
• I fixed a really bad bug with monitors set or limited to 16 colors. The fade routines were assuming that all the monitors were set to 256 colors. So, when a monitor was set to 16 colors it was going out and changing the memory locations for 240 colors that did not exist. Needless to say, this corrupted the system heap and caused an almost immediate system crash. I fixed it by limiting the loops to the size of the devices color table.
• Even though I can't prove it, I think the fade_to_black function was only fading 255 instead of 256 color indices. But since the last color in the system color table is black, no one noticed.
• I tried to clean up the code a little bit. Most of it came about from the bug fixes and integrating Macneil's code.
• The Fade Tester application has been upgraded to include a demo of Macneil's function and contains some useful examples of its use. It basically loads some clut resources and fades to them. There is also an example of manipulating an existing color table and fading to it. These examples probably only just begin to tap the power of this function. If you find a cool use for it, both Macneil and myself would love to hear from you.
Notes
• Knowing the size of your color tables in very important. For the fade_to_clut() routine, you don't want to send a 256 color table to a 16 color device. You will hang, or at least I did. Either make sure the device is set to the depth of your color tables or limit your color tables to the depth of the device. There is an example of limiting your color tables in the Fade Tester application.
• The Clut Fade routines are limited to 256 color max. If your device is set to thousands or millions of colors, it probably won't work well.
The Future
• Integrating the fade_to_black and fade_to_clut into one routine with multiple monitor support. After all, black is just another color.
• Macneil sent me a preliminary version of some code that performs a picture-to-picture fade. Not some goofy pixel fade like in HyperCard, but a clut kind of fade. When he feels it is ready, hopefully he'll integrate it. Let him know if you would find it useful.
So, what is new? The original code only performed the fade on the main screen. It was a great jumping off point for what I wanted in my game code. Sometimes I'd like to fade all of the monitors, or maybe all the monitors except the main monitor.
For example, I see the following steps happening:
1. User launches game and all monitors fade to black.
2. The main monitor fades to the first game screen (all other screens are still black).
3. The main monitor fades between various screens in the game.
4. User quits game, and all the monitors fade back to original contents.
With this in mind, I modified the code to accept a new flag parameter to fade the main monitor only, all the monitors, or all the monitors except the main monitor. Inside Jonas' original code I added some loops that work with each gDevice connected. I also removed almost all the globals that were previously used. My modifications would have significantly grown the global data, so I made it all local to the fade routine. The 1.0 code was very well written and made it a snap to make my modifications.
The clut_fade routines are now in their own project that is used by the Fade Tester 1.0 project to demonstrate the features.
Ken Long suggested a modification where you can fade to other colors besides black. I didn't get a chance to look into it. Maybe someone out there can take it to that next step.
